*** IMPORTANT *** IMPORTANT *** IMPORTANT *** IMPORTANT ***
The USB Support and USB Device Extension files may not be distributed
in any manner. These files are for developer use only, and are NOT
TO BE INCLUDED with the components installed with your product.
This DDK requires that you have the Universal Interfaces and Libraries 3.3.1 installed in your development environment. You can obtain these files from the Apple Developer Connection SDK web page:
<http://developer.apple.com/sdk>
The two common symptoms that you have not yet installed these files will be:
1. There is a compile time error that the header file "MacErrors.h" could not be found
2. There is a link error that the file HIDLib could not be found.
Both files are included with Universal Interfaces and Libraries 3.3.1.
Refer to the document "MacOS USB Change History -> 1.2" for the Change History of Mac OS USB up to version 1.2.
For Macintosh Systems with built-in USB, you should test with Mac OS 9.0.4 installed. Ideally, you should test with the Mac OS update to System 9.0.x installed if you have access to the Apple Developer Relations Seed Site. Use the Software Update Control Panel built into Mac OS 9 to download the software update. Alternatively, you can test with the System Extension files supplied as part of this DDK. However, if you encounter a problem, you will need to verify whether the problem still occurs with Mac OS 9.0.4 before submitting a bug report. Refer to the Installation instructions provided in the "Mac OS USB DDK Readme" to test with the Extension files. Important note: Mac OS USB 1.4.6 will only be available on systems with the update to Mac OS 9.0.4 installed.
Note that USB audio support requires Mac OS 9.0 or later on a Macintosh system with built-in USB to function properly.
Please make no assumption as to the release of Mac OS USB indicating the presence of a specific version of Mac OS System Software.
Testing USB 1.4.6f4 on older Power Macintosh systems without built-in USB
For Macintosh Systems which do no have built-in USB, but have an installed USB PCI or Cardbus card present, follow the instructions presented in the Mac OS USB DDK Readme document.
Changes from USB 1.4.3 -> 1.4.6
-------------------------------
Developer Tools
- New HID Browser, fixed buttons displays.
Comm Class Driver
- Fixed problem that would cause devices returning STALL to SET_INTERFACE to fail to initialize
USB Family Expert
- Added support for multiple driver descriptors in a USB Class Driver. We now look for an exported symbol "The USBDriverDescriptionCount", and if found, retrieve its value and treat the 'TheUSBDriverDescription' as an array with that many elements. If the symbol is not found, treat 'TheUSBDriverDescription' as having only a single entry. This change makes it possible to write a driver which supports multiple devices with a single driver in the presence of USB 1.4.6 or later. For compatibility with older releases of USB, set the first 'TheUSBDriverDescription' record with the match criteria for the primary device which the driver supports.
USB.h file
- Removed support for "OLDCLASSNAMES"
USB Composite Class Driver
- Helped composite driver replacement for slow devices. Fixes some problems with devices that fail to work if attached at boot time, but work when hot-plugged.
USBKeypad (DDK Sample Driver)
- Changed the sample code to use BlockMoveData (instead of slower BlockMove).
Storage Class Driver (DDK Sample Driver)
- Reverted the driver's dispatch table name to the generic name to be compatible with shim.
- Change the shim to properly use USBGetDriverConnectionID.
- Changed the Unit table driver code to use BlockMoveData.
HID Driver
- Changed the driver to use BlockMoveData instead of BlockMove.
HUB Driver
- Changed the driver to use BlockMoveData instead of BlockMove.
OHCI UIM
- Fixed a problem that caused root-hub interrupts to be lost (hot plugging didn't work with PCI cards).
PrinterClass Driver
- Changed the driver and sample to use BlockMoveData instead of BlockMove.
Printer Chooser example
- Changed the sample code to use BlockMoveData instead of BlockMove.
USB Family Expert
- Added Logging messages to SendDeviceNotification.
- Added logging messages when notifications aren't send because of bad descriptor data
Keyboard Shim
- Weak link to power manager to allow load on old (PDM) machines.
DropPrint example
- remove obsolete definition of QDGlobals.
USB 1.4.2
---------
USB 1.4.2 addresses only a single issue regarding the USB hubs on the Apple Studio Displays being unusable upon the system awakening from sleep. For this release, the Gestalt selector 'usbv' returns 0x01428000. Note that the version of the USB Device Extension file remains 1.4.1. USB 1.4.2 is included as part of Mac OS 9.0.4. There is no standalone installer nor separate extensions provided for testing of this release. You can only test with this release of USB by installing Mac OS 9.0.4.
Changes from USB 1.4.1 -> 1.4.3
-------------------------------
Comm Class Driver
- Removed baud-rate lock (DTE rate was 115k baud always).
Composite Class Driver
- Suppress repeating not-terminating messages.
DDK
- New StorageClassSample added.
- New PowerClassQueryDevice sample added.
- Added Readme's to PrinterClass and PowerClassQueryDevice examples.
HID Driver
- Make sure we won't call any HIDGetReport handlers after a call the HIDCloseDevice
- Added HIDGetIndexedString function. This function is used to get a string directly from a HID device.
- Fixed slow updating from certain HID devices.
- Fixed some occasional mouse/keyboard failures when using certain hubs.
HID Library
- Added new "Capabilities" functions that clients can find the units and exponents of various values.
- Fixed problems with complex report decriptors that was leading to failures with keyboards that had lots of LEDs.
Hub Class Driver
- Improve driver tracing, use hub verbosity bit in Expert Options to enable.
- Fixed reset error recovery failure
- Return correct error from port reset when set address fails.
OHCI UIM
- Remove Isoc error messages on short packets
- BulkTransfer split into two parts (setup and allocating the transfer descriptors). This will allow us to remove the artificial limit of 4K for control transactions.
- Added descriptive expert log text for Isoch errors.
Power Class Driver
- Fixed problem with invalid values returned before the device provided any updates.
Printer Class Driver
- Weak link to USBExpertStatusLevel to allow use with old versions of USB.
- Only use USB suspend/resume if the version of USB supports that functionality.
- Turned off LOCK_MEMORY flag, since it's not needed with double-buffering.
SerialShimLib
- Added SetFlags & GetGlobals entry points
USB Expert
- Suppress repeating deferred termination messages in the USB expert log.
- Added mechanism for ADB Shim to discover keyboard information from third parties (USBConfigureADBShim)
USBServicesLib
- Fixed problem were an immediate UIM error could be placed on the wrong queue (and thus the callback would never occur).
- Fixed problem with USBGetStringDescriptor. If a device returned an error (such as a STALL) in response to the request to read the length bytes, we would call the completion routine then continue to try reading the string, thus calling the completion routine a second time. Since drivers typically don't ask for strings the device doesn't support, this may not be that big of a problem.
- Added checks for delayed callbacks, reduced unnecessary messages.
- Fixed problem when handling some immediate errors in our queues. Should result in more reliable operation.
Changes from USB 1.4 -> 1.4.1f4
-------------------------------
1. Implemented a fix for printer class devices where a suspend request to the interface driver resulted in suspending the entire device.
2. Fixed the "jerky cursor" problem which occurred whenever the USB mouse was used during disk activity. The problem was especially noticeable on PowerBook system whenever the internal drive had gone to sleep and was being spun ap.
3. Fixed a problem in which waking up a PowerBook G3 Series system with a USB Cardbus card present would lose USB services.
4. Implemented the following HID routines
HIDGetNextButtonInfo
HIDGetNextUsageValueInfo
HIDGetReportLength
HIDInitReport
5. Fixed the HID Driver to return the serial string when passed the HIDGetDeviceInfo request with the kHIDGetInfo_GetSerialNumberString selector.
6. Include the HID Reader utility (which based on the HID Reader sample code, but is far more extensive a program).
7. Include the PowerClassQueryDevice sample program.
8. USB now checks for the presence of the 'dbex' resource to allow disabling of file based drivers if the Shift key is held down at startup.
9. Fixed a memory corruption problem in the HID driver when it would allocate memory during interrupt time.
10. Updated the PrintClassDriver to work with all releases of USB 1.1 and greater. Also fixed a problem with the DrvrGlue.a.o where the older code was still being used even though the .a code had been updated. Separated the PrinterDriver from the Chooser portion of the sample.
11. Fixed a problem with USBProber such that it was not displaying the driver version string correctly.
Changes from USB 1.3.5f8 -> 1.4
-------------------------------
1. Added feature for a USBShim to be registered as a shared library. USBShim must export the symbol "ShimDescription" which is a structure of type USBShimDescription where the USBShimLoadingOptions field must have the kUSBRegisterShimAsSharedLibrary bit set, and the libraryName field defines the CFM shared library name.
2. Added support for the HIDDriver HIDGetReport and HIDSetReport API's.
3. The OHCI UIM has been modified so that the root hub simulation is interrupt based instead of polled. Other changes were made to the USB keyboard and pointing devices to work with Macsbug.
4. Fixed a buffer overrun situation with the USB Audio class driver which resulted in the corruption of the heap. The common symptom was that USB microphones would work for a period of time, but then input would stop.
5. Implemented several fixes in the USB Audio class for compatibility with audio input and output devices.
6. Fixed an error-recovery problem in the Printer class driver.
7. Modified USB Family Expert to report better error messages when a driver fragment fails to load.
8. Modified the HID class driver for compatibility with USB 1.1.
8. Added support to the HID class driver for some digitizer tablets.
9. Exported the USBAddShimFromDisk function from the USB Family Expert so that this call now works properly.
10. USB Shims and Drivers can now be in either 'usbd' or 'usbs' files.
11. Added API call USBSetPipePolicy to allow changing pipe characteristics. This call will be better documented in a future version of this readme. Some things that can be controlled -
Max number of bytes per frame. Allows Isoc devices to use less than bandwidth specified in the endpoint.
Max data per IRP. Basically the max that usbReqCount can be. This is currently not implemented.
Max service interval. For Interrupt endpoints, this is the polling interval.
12. Added API call to obtain the USB String Descriptor
OSStatus USBGetStringDescriptor(USBPB *pb)
--> usbReference Device/Interface
--> usb.cntl.WValue String number
--> usb.cntl.WIndex Language code, 0 for English
--> usbBuffer Where to put descriptor
--> usbReqCount Size of buffer
<-- usbActCount Size of returned string
13. Fixed problem with suspend and resume so that transactions are processed correctly.
14. Removed support in the Audio class driver for 4.000 kHz and 8.000 kHz sampling rates.
15. Moved USB.h to the Interfaces folder. Added HID.h to the Interfaces folder.
16. Added API call to obtain the bandwidth available to an isochronous device.
OSStatus USBGetBandwidthAvailableByReference
--> usbReference device/interface/pipe on bus
<-- avail currently available bandwidth
17. Added the kUSBDebugAwareFlag to USB.h. This is used by drivers that want a transfer to complete while Macsbug is active. Typically this will just be keyboard/mouse drivers. The use of this flag will be documented later. In order for Macsbug to work properly with modules which implement this flag, the next version of the MacOS ROM file is required.
18. Fixed a problem with the Audio class driver such that the mouse was jerky with audio active.
19. Fixed a problem with the USB CardBus Enabler so that the UIM is unloaded before the card is ejected.
20. The HID class driver checks for USB versions earlier than 1.1 and refuses to load.
21. Addessed a crash problem with hot-plugging devices to a CMD 670/673 USB PCI card.
22. Added API call, USBPortStatus
OSStatus USBPortStatus(USBPB *pb)
--> usbReference Device/Interface
<-- usbStatus result of query.
The result of the query is most likely to be:
noErr nothing is wrong, transient error
kUSBDeviceDisconnected the device is no longer connected
kUSBPortDisabled port device is disabled. A reset is needed.
The USBPortStatus call is designed to be used when a driver gets a kUSBNotResponding error, to find out why this error occurred. This will distinguish between a transient error, that where the device is disconnected, and the condition where the driver's port has been disabled because of a babble condition (can be caused by ESD).
In response, if the device is disconnected the the Apple class drivers have been modified to stop communications with the device and prepare to be cleaned up. If the port is disabled, the class drivers will reset the device and go back into their configuration routines.
23. Included the USB Software Locator technote #1191, along with various tools for creating an Installer script and for testing the software update from the USB staging server.
24. Added Expert Options Control Panel to allow control of a. the default Expert Status level, b. the size of the Expert Status message buffer, and c. and to force USB to assign fixed addresses to devices. This latter option means that if the USB topology remains unchanged across reboots, then each device will be assigned the same USB address.
25. Added Power Class driver to the USB Device Support driver file. Along with this support are the addition of the following API's in the PowerClass.h file
These calls will be documented in an upcoming version of this readme. Use of these calls requires linking with the USBPowerClassLib stub library.
26. Modifed reporting of overcurrent cases to eliminate false overcurrent indications for USB Hubs.
27. Implement fix to USB Software Locator to provide region information to the server. A fix to the server is still required for the correct support of localized software via USB Software Locator. At present, only International English packages are offered to users regardless of the localized system software they are using.
28. Removed the Apple specific mouse driver as the generic mouse class driver correctly handles support of this device.
29. Added the USBPowerGetCapacityLimits and the USBPowerGetCapacityLimits calls to get/modify the control limits which are passed to the Power Manager which govern when the low power alert is raised for a USB Power Class device.
30. The USL Services Library now exports the USBSetPipePolicy call.
31. Improved interaction with USB Cardbus card when the card is ejected with USB devices attached, then reattached. Previously, if a USB device was connected to the USB Cardbus card and the card ejected, then re-inserted, the devices would stop functioning.
32. Fixed problem with Keyboard class driver such that when awakening from sleep, the system would hang when multiple attempts were made to set the LED's.
33. Fixed a longstanding name registry name corruption problem which occurred with the Lexmark Z51 printers only.
34. Modified the USBAddDriverFromFSSpec call so that an error is returned if the previous driver could not be unloaded immediately. This can happen if the current module does not allow the finalize routine to be called immediately. In such case, the kUSBDeviceBusy error is returned. If this happens, then it is the responsiblity of the caller to give the system some task time so that the module can complete any necessary processing at task time an allow the finalize routine to be called. The psuedo code for making the USBAddDriverForFSSpec call is as follows.
err = USBAddDriverForFSSpec();
while (err == kUSBDeviceBusy)
{
give system some idle time (WaitNextEvent())
err = USBAddDriverForFSSpec();
if we've looped "long enough", bail out
}
35. Fixed a crash when using USB microphones with ViaVoice, by setting the default sample rate for input devices.
36. Fixed a problem whereby a USB mouse quits working after an ADBReInit call on machines without the ADBShim present. The ADBShim is present on all Macintosh system that have USB built-in.
37. Fixed USBResetDevice so that it no longer corrupts memory past the parameter block. For USB 1.3 and earlier, the call to USBResetDevice would overwrite memory up to 96 bytes past the end of the parameter block. For USB 1.3.x and earlier, one workaround is to append a pad of 96 bytes to a USBPB structure which you pass to USBResetDevice.
38. Modified USBProber so that the bus probe window is not updated on every notification.
39. Fixed a problem with the Modem Class Driver which closed the connection to the SerialShimLib if the system was put to sleep, even if the application using the USB Modem, had not closed the connection.
40. Modified the USBKeyypad example code to support the ForceQuit key sequence on cpu's without the ADBShim present.
41. Updated the USB API Reference to v26 which includes a description of the new calls and API's.
42. USB audio support now provided for 16-bit mono USB Audio input devices. Requires Mac OS 9.0.4.
Changes from USB 1.2 -> 1.3.5f8
-------------------------------
1. Added support for driver requested timeouts.
2. Implemented support in the HID driver to support vendor-specific drivers for Immersion-based force feedback joysticks.
3. Implemented support for the USB Expert to get the international strings from a USB device.
4. Provide USB suspend and resume wakeup support.
5. Fixed bug where device names were not showing up when the "not enough power" dialog was displayed.
6. USBExpertStatus calls are now re-entrant. This should solve some "missing messages" reported by some driver writers.
7. Modified USBProber to size the vertical scrollbars correctly. Fixed "flashing" problem when the expert log would overflow.
8. Added new functions allowing USB Class Drivers to get and set the Expert Status level. This will allow developers to debug specific problems they are experiencing and not overflow the log. This functionality is currently only used by USB Prober.
9. Added support for kNotifySystemSleepRevoke message.
10. Improved the performance of isochronous and interrupt transfer routines under Virtual Memory.
11. CHANGE FOR 1.3a4 from previous builds - Added support for 5-second timeout functionality for Control Endpoint only. If a device fails to transfer data for 5 seconds on the Control Endpoint (ie, NAKs continiously), then the transfer will be returned. We still permit the kUSBNo5SecTimeout flag for bulk transactions -- but we intend disallow this in a future build. -- PLEASE UPDATE YOUR DRIVERS IF YOU HAVE BEGUN TO USE THIS FLAG!
12. Fixed a problem that could permit dereferencing nil if we ran out of isoch descriptors.
13. Implemented the USBGetVersion call to obtain the version of USB present. This call is provided as an alternative for using Gestalt so that one did not need to link with InterfaceLib in order to obtain the version of USB present. The following is a sample call to demonstrate how to do this. For this example, you weak link the USBServicesLib as part of the project. The result of the call is a 4 byte 'vers' response exactly like what would be returned by using the Gestalt call with the 'usbv' selector.
#include <USB.h> // ensure that you include the USB.h 1.3 header file
UInt32 MyUSBGetVersion(void)
{
UInt32 version;
if ((Ptr) USBGetVersion != (Ptr) kUnresolvedCFragSymbolAddress)
version = USBGetVersion();
else
version = 0; // version of USB is less than 1.3
return version;
}
14. USBExpertStatus and USBExpertStatusLevel are now more efficient, if the message does not appear in the USB Prober log. USB Prober now checks the level parameter before processing the message. Before, USB Prober checked the level just before inserting the message in the log.
15. Fixed the Isochronous frStatus error codes. In USB 1.2 (and earlier) the wrong error codes were returned. For example a DataOverRun error would appear as a Stall error, and DeviceNotResponding was reported as a BitStuff error.
16. Fixed a problem with the OHCIUIM in which multiple overcurrent dialogs appeared when the root hub detected an overcurrent situation.
17. Made sure that the kNotifySystemSleepDemand messages are sent the the driver modules.
18. Fixed the Mouse driver to function better on USB CardBus-equipped PowerBooks.
19. For USB.h 1.3b3, updated the USB.h header with the correct defines for selecting timeouts when no-data is being transferred.
20. Added support for specifying timeouts when no-data is being transferred.
21. Updated the USB_API_Ref from v23 to v24v4.
22. API Addition - added the USBAddDriverForFSSpec function call. Refer to the v24v4 USB_API_Ref for a description of this call.
23. Fix out-of-order transactions that could occur on immediate errors from the UIM.
24. Implemented a fix to the StorageClass sample driver to address a problem when trying to write greater than 2MB to the disk.
25. Implemented a fix for a re-entrancy problem which occurred with some audio devices when doing a rapid hot-plug/unplug test.
26. Improved error handling in the printer driver.
27. Fixed problem wuch that drivers were reporting a status of USBPending.
28. Added the following class drivers to the USB Device Extension file
USBHIDDriver - support for HID class devices, subclass 0
USBHIDDriver1 - support for HID class devices, subclass 1
USBCommClassDriver - supports USB Comm Class devices, subclass "Abstract Control Model", protocol V.25.
USBAudioClassDriver - requires SSW 9.0
USBAudioStreamDriver - requires SSW 9.0
USBPrintingSupport
plus a number vendor specific modules for force feedback game devices.
29. Updated the USBManagerLib to include the USBAddShimFromDisk call.
30. Included the USB Software Locator Extension as part of the DDK. This extension is required for Mac OS 9.0 on PCI Power Macintosh Systems which do not have USB built-in. This extension works with the Software Locator to download USB drivers from the Internet for devices for which no matching driver is found. The USB Software Locator extension does nothing if installed over Mac OS 8.6. A Tech Note (#1191) has been released which discusses how developers can provide support for the USB Software Locator mechanism <http://developer.apple.com/technotes/tn/tn1191.html>.
Known Issues with USB 1.3.5
---------------------------
1. The iBook, iMac DV, and the Power Macintosh G4 systems with AGP support USB Mass Storage devices at startup. If media is present when the system is started, the driver loaded from ROM will not be replaced by a Mass Storage driver located in the Extensions folder, if present. On the other hand, if the media (like a Zip disk) is inserted after the system has booted, then the disk-based driver will be used.
If there is a need to force the vendor specific storage class driver to be used, one can make the USBAddDriverForFSSpec call. One important note on the use of this call, you must pass in the USBReference num for the USBDeviceReference, and the FSSpec must be for a correcsponding device class driver. For the storage class case, set the USBReference number to the composite class driver which has loaded the storage class interface. The FSSpec record must point to USB Device Support file which contains the composite class driver.
